/*
 * Copyright (c) 1994, 2012, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang;

/**
 * {@code Object} 类是类层次结构的根。
 * 每个类都以 {@code Object} 作为超类。所有对象，
 * 包括数组，都实现了这个类的方法。
 *
 * @author  unascribed
 * @see     java.lang.Class
 * @since   JDK1.0
 */
public class Object {

    private static native void registerNatives();
    static {
        registerNatives();
    }

    /**
     * 返回此 {@code Object} 的运行时类。返回的
     * {@code Class} 对象是被所表示类的 {@code
     * static synchronized} 方法锁定的对象。
     *
     * <p><b>实际的结果类型是 {@code Class<? extends |X|>}，
     * 其中 {@code |X|} 是调用 {@code getClass} 的表达式的
     * 静态类型的擦除。</b> 例如，在这个代码片段中不需要强制转换：</p>
     *
     * <p>
     * {@code Number n = 0;                             }<br>
     * {@code Class<? extends Number> c = n.getClass(); }
     * </p>
     *
     * @return 表示此对象运行时类的 {@code Class} 对象。
     * @jls 15.8.2 Class Literals
     */
    public final native Class<?> getClass();

    /**
     * 返回该对象的哈希码值。支持此方法是为了
     * 提高哈希表（如 {@link java.util.HashMap} 提供的哈希表）的性能。
     * <p>
     * {@code hashCode} 的通用约定是：
     * <ul>
     * <li>在 Java 应用程序执行期间，在对同一对象多次调用 hashCode 方法时，
     *     必须一致地返回相同的整数，前提是将对象进行 {@code equals} 比较时
     *     所用的信息没有被修改。从某一应用程序的一次执行到同一应用程序的
     *     另一次执行，该整数无需保持一致。
     * <li>如果根据 {@code equals(Object)} 方法，两个对象是相等的，
     *     那么对这两个对象中的每个对象调用 {@code hashCode} 方法
     *     都必须生成相同的整数结果。
     * <li>如果根据 {@link java.lang.Object#equals(java.lang.Object)}
     *     方法，两个对象不相等，那么对这两个对象中的任一对象上调用
     *     {@code hashCode} 方法<em>不</em>要求一定生成不同的整数结果。
     *     但是，程序员应该意识到，为不相等的对象生成不同整数结果
     *     可以提高哈希表的性能。
     * </ul>
     * <p>
     * 实际上，由 {@code Object} 类定义的 hashCode 方法确实会针对
     * 不同的对象返回不同的整数。（这一般是通过将该对象的内部地址
     * 转换成一个整数来实现的，但是 Java&trade; 编程语言不需要
     * 这种实现技巧。）
     *
     * @return  此对象的一个哈希码值。
     * @see     java.lang.Object#equals(java.lang.Object)
     * @see     java.lang.System#identityHashCode
     */
    public native int hashCode();

    /**
     * 指示其他某个对象是否与此对象"相等"。
     * <p>
     * {@code equals} 方法在非空对象引用上实现相等关系：
     * <ul>
     * <li>它是<i>自反的</i>：对于任何非空引用值 {@code x}，
     *     {@code x.equals(x)} 都应返回 {@code true}。
     * <li>它是<i>对称的</i>：对于任何非空引用值 {@code x} 和 {@code y}，
     *     当且仅当 {@code y.equals(x)} 返回 {@code true} 时，
     *     {@code x.equals(y)} 才应返回 {@code true}。
     * <li>它是<i>传递的</i>：对于任何非空引用值 {@code x}、{@code y} 和 {@code z}，
     *     如果 {@code x.equals(y)} 返回 {@code true}，
     *     并且 {@code y.equals(z)} 返回 {@code true}，
     *     那么 {@code x.equals(z)} 应返回 {@code true}。
     * <li>它是<i>一致的</i>：对于任何非空引用值 {@code x} 和 {@code y}，
     *     多次调用 {@code x.equals(y)} 始终返回 {@code true}
     *     或始终返回 {@code false}，前提是对象上 {@code equals}
     *     比较中所用的信息没有被修改。
     * <li>对于任何非空引用值 {@code x}，
     *     {@code x.equals(null)} 都应返回 {@code false}。
     * </ul>
     * <p>
     * {@code Object} 类的 {@code equals} 方法实现对象上差别可能性最大的
     * 相等关系；即，对于任何非空引用值 {@code x} 和 {@code y}，
     * 当且仅当 {@code x} 和 {@code y} 引用同一个对象时，
     * 此方法才返回 {@code true}（{@code x == y} 具有值 {@code true}）。
     * <p>
     * 注意：当此方法被重写时，通常有必要重写 {@code hashCode} 方法，
     * 以维护 {@code hashCode} 方法的常规协定，该协定声明
     * 相等对象必须具有相等的哈希码。
     *
     * @param   obj   要与之比较的引用对象。
     * @return  如果此对象与 obj 参数相同，则返回 {@code true}；
     *          否则返回 {@code false}。
     * @see     #hashCode()
     * @see     java.util.HashMap
     */
    public boolean equals(Object obj) {
        return (this == obj);
    }

    /**
     * 创建并返回此对象的一个副本。"副本"的准确含义
     * 可能依赖于对象的类。这样做的目的是，对于任何对象 {@code x}，表达式：
     * <blockquote>
     * <pre>
     * x.clone() != x</pre></blockquote>
     * 为 true，表达式：
     * <blockquote>
     * <pre>
     * x.clone().getClass() == x.getClass()</pre></blockquote>
     * 也为 {@code true}，但这些并非必须要满足的条件。
     * 一般情况下，表达式：
     * <blockquote>
     * <pre>
     * x.clone().equals(x)</pre></blockquote>
     * 为 {@code true}，但这并非必须要满足的条件。
     * <p>
     * 按照惯例，返回的对象应该通过调用 {@code super.clone} 获得。
     * 如果一个类及其所有的超类（除 {@code Object} 外）都遵守此约定，
     * 则 {@code x.clone().getClass() == x.getClass()}。
     * <p>
     * 按照惯例，此方法返回的对象应该独立于该对象（正在被克隆的对象）。
     * 要获得此独立性，在 {@code super.clone} 返回对象之前，
     * 有必要对该对象的一个或多个字段进行修改。这通常意味着要复制包含正在被克隆对象的
     * 内部"深层结构"的所有可变对象，并使用对副本的引用替换对这些对象的引用。
     * 如果一个类只包含基本字段或对不变对象的引用，那么通常不需要修改
     * {@code super.clone} 返回的对象中的字段。
     * <p>
     * {@code Object} 类的 {@code clone} 方法执行特定的克隆操作。
     * 首先，如果此对象的类不能实现 {@code Cloneable} 接口，则会抛出
     * {@code CloneNotSupportedException}。注意，所有的数组都被视为实现接口
     * {@code Cloneable}，并且数组类型 {@code T[]} 的 {@code clone} 方法的
     * 返回类型是 {@code T[]}，其中 T 是任何引用或基本类型。
     * 否则，此方法会创建此对象的类的一个新实例，并像通过赋值那样，
     * 用此对象相应字段的内容对其所有字段进行初始化；这些字段的内容本身并不被克隆。
     * 所以，此方法执行的是该对象的"浅表复制"，而不"深层复制"操作。
     * <p>
     * {@code Object} 类本身不实现 {@code Cloneable} 接口，
     * 所以在类为 {@code Object} 的对象上调用 {@code clone} 方法
     * 将会导致在运行时抛出异常。
     *
     * @return     此实例的一个克隆。
     * @throws  CloneNotSupportedException  如果对象的类不支持 {@code Cloneable}
     *               接口。重写 {@code clone} 方法的子类也可以
     *               抛出此异常，以指示无法克隆某个实例。
     * @see java.lang.Cloneable
     */
    protected native Object clone() throws CloneNotSupportedException;

    /**
     * 返回该对象的字符串表示。通常，{@code toString} 方法会返回一个
     * "以文本方式表示"此对象的字符串。结果应是一个简明但易于读懂的信息表达式。
     * 建议所有子类都重写此方法。
     * <p>
     * {@code Object} 类的 {@code toString} 方法返回一个字符串，
     * 该字符串由类名（对象是该类的一个实例）、at 标记符"@"和此对象
     * 哈希码的无符号十六进制表示组成。换句话说，该方法返回一个字符串，
     * 它的值等于：
     * <blockquote>
     * <pre>
     * getClass().getName() + '@' + Integer.toHexString(hashCode())
     * </pre></blockquote>
     *
     * @return  该对象的字符串表示形式。
     */
    public String toString() {
        return getClass().getName() + "@" + Integer.toHexString(hashCode());
    }

    /**
     * 唤醒在此对象监视器上等待的单个线程。
     * 如果所有线程都在此对象上等待，则会选择唤醒其中一个线程。
     * 选择是任意性的，并在对实现做出决定时发生。线程通过调用其中一个
     * {@code wait} 方法，在对象的监视器上等待。
     * <p>
     * 直到当前线程放弃此对象上的锁定，才能继续执行被唤醒的线程。
     * 被唤醒的线程将以常规方式与在该对象上主动同步的其他所有线程进行竞争；
     * 例如，唤醒的线程在作为锁定此对象的下一个线程方面没有可靠的特权或劣势。
     * <p>
     * 此方法只应由作为此对象监视器的所有者的线程来调用。
     * 通过以下三种方法之一，线程可以成为对象监视器的所有者：
     * <ul>
     * <li>通过执行此对象的同步实例方法。
     * <li>通过执行在此对象上进行同步的 {@code synchronized} 语句的正文。
     * <li>对于 {@code Class} 类型的对象，通过执行该类的同步静态方法。
     * </ul>
     * <p>
     * 一次只能有一个线程拥有对象的监视器。
     *
     * @throws  IllegalMonitorStateException  如果当前线程不是此对象监视器的所有者。
     * @see        java.lang.Object#notifyAll()
     * @see        java.lang.Object#wait()
     */
    public final native void notify();

    /**
     * 唤醒在此对象监视器上等待的所有线程。
     * 线程通过调用其中一个 {@code wait} 方法，在对象的监视器上等待。
     * <p>
     * 直到当前线程放弃此对象上的锁定，才能继续执行被唤醒的线程。
     * 被唤醒的线程将以常规方式与在该对象上主动同步的其他所有线程进行竞争；
     * 例如，被唤醒的线程在作为锁定此对象的下一个线程方面没有可靠的特权或劣势。
     * <p>
     * 此方法只应由作为此对象监视器的所有者的线程来调用。
     * 有关线程能够成为监视器所有者的方法的描述，请参阅 {@code notify} 方法。
     *
     * @throws  IllegalMonitorStateException  如果当前线程不是此对象监视器的所有者。
     * @see        java.lang.Object#notify()
     * @see        java.lang.Object#wait()
     */
    public final native void notifyAll();

    /**
     * 在其他线程调用此对象的 {@link java.lang.Object#notify()} 方法或
     * {@link java.lang.Object#notifyAll()} 方法，或者超过指定的时间量前，
     * 导致当前线程等待。
     * <p>
     * 当前线程必须拥有此对象监视器。
     * <p>
     * 此方法导致当前线程（称之为 <var>T</var>）将其自身放置在对象的等待集中，
     * 然后放弃此对象上的所有同步要求。出于线程调度目的，在发生以下四种情况之一前，
     * 线程 <var>T</var> 被禁用，且处于休眠状态：
     * <ul>
     * <li>其他某个线程调用此对象的 {@code notify} 方法，并且线程 <var>T</var>
     * 碰巧被任选为被唤醒的线程。
     * <li>其他某个线程调用此对象的 {@code notifyAll} 方法。
     * <li>其他某个线程{@linkplain Thread#interrupt() 中断}线程 <var>T</var>。
     * <li>大约已经到达指定的实际时间。但是，如果 {@code timeout} 为零，
     * 则不考虑实际时间，在获得通知前该线程将一直等待。
     * </ul>
     * 然后，线程 <var>T</var> 从对象的等待集中被移除，并重新启用线程调度。
     * 然后，该线程以常规方式与其他线程竞争，以获得在该对象上同步的权利；
     * 一旦获得对该对象的控制权，该对象上的所有其同步声明都会被恢复到以前的状态，
     * 这就是调用 {@code wait} 方法时的状况。然后，线程 <var>T</var> 从
     * {@code wait} 方法的调用中返回。所以，从 {@code wait} 方法返回时，
     * 该对象和线程 {@code T} 的同步状态与调用 {@code wait} 方法时的情况完全相同。
     * <p>
     * 线程也可以不被通知、中断或超时而唤醒，这就是所谓的<i>虚假唤醒</i>。
     * 虽然这种情况在实践中很少发生，但是应用程序必须通过以下方式防范它：
     * 对应该导致该线程被提醒的条件进行测试，如果不满足该条件，则继续等待。
     * 换句话说，等待应总是发生在循环中，如下面的示例：
     * <pre>
     *     synchronized (obj) {
     *         while (&lt;condition does not hold&gt;)
     *             obj.wait(timeout);
     *         ... // Perform action appropriate to condition
     *     }
     * </pre>
     * （有关这个主题的更多信息，请参阅 Doug Lea 撰写的 "Concurrent Programming in Java (Second Edition)" 
     * (Addison-Wesley, 2000) 中的第 3.2.3 节，或 Joshua Bloch 撰写的 
     * "Effective Java Programming Language Guide" (Addison-Wesley, 2001) 中的第 50 项。
     *
     * <p>如果当前线程在等待之前或在等待时被任何线程{@linkplain java.lang.Thread#interrupt() 中断}，
     * 则会抛出 {@code InterruptedException}。在按上述形式恢复此对象的锁定状态时才抛出此异常。
     *
     * <p>
     * 注意，由于 {@code wait} 方法将当前线程放入此对象的等待集中，所以它只能解除此对象的锁定；
     * 可以同步当前线程的任何其他对象在线程等待时仍处于锁定状态。
     * <p>
     * 此方法只应由作为此对象监视器的所有者的线程来调用。
     * 有关线程能够成为监视器所有者的方法的描述，请参阅 {@code notify} 方法。
     *
     * @param      timeout   以毫秒为单位的最长等待时间。
     * @throws  IllegalArgumentException      如果 timeout 值为负。
     * @throws  IllegalMonitorStateException  如果当前线程不是此对象监视器的所有者。
     * @throws  InterruptedException 如果在当前线程等待通知之前或者正在等待通知时，
     *             任何线程中断了当前线程。在抛出此异常时，当前线程的<i>中断状态</i> 被清除。
     * @see        java.lang.Object#notify()
     * @see        java.lang.Object#notifyAll()
     */
    public final native void wait(long timeout) throws InterruptedException;

    /**
     * 在其他线程调用此对象的 {@link java.lang.Object#notify()} 方法或
     * {@link java.lang.Object#notifyAll()} 方法，或者其他某个线程中断当前线程，
     * 或者已超过某个实际时间量前，导致当前线程等待。
     * <p>
     * 此方法类似于一个参数的 {@code wait} 方法，但它允许更好地控制在放弃之前等待通知的时间量。
     * 用毫微秒度量的实际时间量可以通过以下公式计算出来：
     * <blockquote>
     * <pre>
     * 1000000*timeout+nanos</pre></blockquote>
     * <p>
     * 在其他所有方面，此方法执行的操作与带有一个参数的 {@link #wait(long)} 方法相同。
     * 需要特别指出的是，{@code wait(0, 0)} 与 {@code wait(0)} 相同。
     * <p>
     * 当前线程必须拥有此对象的监视器。该线程发布对此监视器的所有权并等待，
     * 直到发生以下两个条件之一：
     * <ul>
     * <li>其他线程通过调用 {@code notify} 方法，或 {@code notifyAll} 方法通知在
     *     此对象的监视器上等待的线程醒来。
     * <li>超出了由 {@code timeout} 毫秒数和 {@code nanos} 毫微秒数指定的超时期限。
     * </ul>
     * <p>
     * 然后该线程等到重新获得对监视器的所有权后才能够继续执行。
     * <p>
     * 对于某一个参数的版本，中断和虚假唤醒是可能的，并且此方法应该始终在循环中使用：
     * <pre>
     *     synchronized (obj) {
     *         while (&lt;condition does not hold&gt;)
     *             obj.wait(timeout, nanos);
     *         ... // Perform action appropriate to condition
     *     }
     * </pre>
     * 此方法只应由作为此对象监视器的所有者的线程来调用。
     * 有关线程能够成为监视器所有者的方法的描述，请参阅 {@code notify} 方法。
     *
     * @param      timeout   以毫秒为单位的最长等待时间。
     * @param      nanos      额外时间，以毫微秒为单位，范围是 0-999999。
     * @throws  IllegalArgumentException      如果 timeout 值是负数，或者 nanos 值不在 0-999999 范围内。
     * @throws  IllegalMonitorStateException  如果当前线程不是此对象监视器的所有者。
     * @throws  InterruptedException 如果在当前线程等待通知之前或者正在等待通知时，
     *             任何线程中断了当前线程。在抛出此异常时，当前线程的<i>中断状态</i> 被清除。
     */
    public final void wait(long timeout, int nanos) throws InterruptedException {
        if (timeout < 0) {
            throw new IllegalArgumentException("timeout value is negative");
        }

        if (nanos < 0 || nanos > 999999) {
            throw new IllegalArgumentException(
                                "nanosecond timeout value out of range");
        }

        if (nanos > 0) {
            timeout++;
        }

        wait(timeout);
    }

    /**
     * 在其他线程调用此对象的 {@link java.lang.Object#notify()} 方法或
     * {@link java.lang.Object#notifyAll()} 方法前，导致当前线程等待。
     * 换句话说，此方法的行为就好像它仅执行 {@code wait(0)} 调用一样。
     * <p>
     * 当前线程必须拥有此对象的监视器。该线程发布对此监视器的所有权并等待，
     * 直到其他线程通过调用 {@code notify} 方法或 {@code notifyAll} 方法
     * 通知在此对象的监视器上等待的线程醒来。然后该线程将等到重新获得
     * 对监视器的所有权后才能够继续执行。
     * <p>
     * 对于某一个参数的版本，中断和虚假唤醒是可能的，并且此方法应该始终在循环中使用：
     * <pre>
     *     synchronized (obj) {
     *         while (&lt;condition does not hold&gt;)
     *             obj.wait();
     *         ... // Perform action appropriate to condition
     *     }
     * </pre>
     * 此方法只应由作为此对象监视器的所有者的线程来调用。
     * 有关线程能够成为监视器所有者的方法的描述，请参阅 {@code notify} 方法。
     *
     * @throws  IllegalMonitorStateException  如果当前线程不是此对象监视器的所有者。
     * @throws  InterruptedException 如果在当前线程等待通知之前或者正在等待通知时，
     *             任何线程中断了当前线程。在抛出此异常时，当前线程的<i>中断状态</i> 被清除。
     * @see        java.lang.Object#notify()
     * @see        java.lang.Object#notifyAll()
     */
    public final void wait() throws InterruptedException {
        wait(0);
    }

    /**
     * 当垃圾回收器确定不存在对该对象的更多引用时，由对象的垃圾回收器调用此方法。
     * 子类重写 {@code finalize} 方法，以释放系统资源或者执行其他清除工作。
     * <p>
     * {@code finalize} 的常规协定是：当 Java&trade; 虚拟机已确定尚未终止的任何线程
     * 无法再通过任何途径访问此对象时，将调用此方法，除非由于准备终止的其他某个对象或类的
     * 终结操作执行了某个操作。{@code finalize} 方法可以采取任何操作，
     * 其中包括再次使此对象对其他线程可用；不过，{@code finalize} 的主要目的是
     * 在不可撤消地丢弃对象之前执行清除操作。例如，表示输入/输出连接的对象的 finalize 方法
     * 可执行显式 I/O 事务，以便在永久丢弃对象之前中断连接。
     * <p>
     * {@code Object} 类的 {@code finalize} 方法执行非特殊性的操作；
     * 它仅执行一些常规返回。{@code Object} 的子类可以重写此定义。
     * <p>
     * Java 编程语言不保证哪个线程将调用某个给定对象的 {@code finalize} 方法。
     * 但可以保证在调用 finalize 时，调用 finalize 的线程将不会持有任何用户可见的同步锁定。
     * 如果 finalize 方法抛出未捕获的异常，那么该异常将被忽略，并且该对象的终结操作将终止。
     * <p>
     * 在启用某个对象的 {@code finalize} 方法后，将不会执行进一步操作，
     * 直到 Java 虚拟机再次确定尚未终止的任何线程无法再通过任何途径访问此对象，
     * 其中包括由其他准备终结的对象或类执行的可能操作，在此情况下，对象可能被丢弃。
     * <p>
     * 对于任何给定对象，Java 虚拟机最多只调用一次 {@code finalize} 方法。
     * <p>
     * {@code finalize} 方法抛出的任何异常都会导致此对象的终结操作停止，但可以通过其他方法忽略它。
     *
     * @throws Throwable 此方法抛出的 {@code Exception}
     * @see java.lang.ref.WeakReference
     * @see java.lang.ref.PhantomReference
     * @jls 12.6 Finalization of Class Instances
     */
    protected void finalize() throws Throwable { }
}
